Import Library Techniques

Inside Macintosh: Mac OS Runtime Architectures /: Chapter 3 - Programming for the CFM-Based Runtime Architecture

Import Library Techniques
Sometimes when you modify an import library, the new version may not remain fully compatible with older versions. As a rule of thumb, the developer should think about compatibility issues for versions of your import libraries in the following cases:

the API for the library changes
the input or output behavior of any library routine changes

There are a number of ways to check or maintain compatibility between successive versions of an import library. Table 3-1 shows some methods for checking or maintaining compatibility. Each method has advantages and disadvantages, and some of them may be used in conjunction with each other.

Table 3-1 Methods for maintaining import library compatibility
Method Advantages Disadvantages
Use no version numbers and no weak symbols No work required at build time. Missing symbols cause program failure.
Declare weak symbols in client Allows limited functionality with whatever symbols are available. Code must check for presence of library exports. Difficult to keep track of all weak symbols.

Use PEF version numbering The Code Fragment Manager automatically checks for compatibility. Program fails if a compatible library is not found. Version numbers can't take into account all possible compatibility cases.
Change names for newer import libraries Eliminates the need for version or symbol checking. Different versions of a library can appear in memory at the same time. Only useful if the newer version cannot support older clients. Multiple names for libraries with similar functionality can be dangerous.
Create an alias library name using multiple 'cfrg'0 entries Allows older clients to use a newer library with a different name. Generally only useful when combining older implementations into one library.
Put new symbols in new logical libraries The functionality of an import library never changes. The number of import library names accumulates over time.
Use reexport libraries Allows older clients to use multiple newer libraries in place of an older one. Generally only useful when an older implementation splits into several newer libraries.

These methods are described more completely in the sections that follow.

Subtopics

Use No Version Numbers and No Weak Symbols

Declare Weak Symbols in Client

Use PEF Version Numbering

Change Names for Newer Import Libraries

Create an Alias Library Name Using Multiple 'cfrg' 0 Entries

Put New Symbols in New Logical Libraries

Use Reexport Libraries

Method	Advantages	Disadvantages
Use no version numbers and no weak symbols	No work required at build time.	Missing symbols cause program failure.
Declare weak symbols in client	Allows limited functionality with whatever symbols are available.	Code must check for presence of library exports. Difficult to keep track of all weak symbols.

Use PEF version numbering	The Code Fragment Manager automatically checks for compatibility.	Program fails if a compatible library is not found. Version numbers can't take into account all possible compatibility cases.
Change names for newer import libraries	Eliminates the need for version or symbol checking. Different versions of a library can appear in memory at the same time.	Only useful if the newer version cannot support older clients. Multiple names for libraries with similar functionality can be dangerous.
Create an alias library name using multiple `'cfrg'0` entries	Allows older clients to use a newer library with a different name.	Generally only useful when combining older implementations into one library.
Put new symbols in new logical libraries	The functionality of an import library never changes.	The number of import library names accumulates over time.
Use reexport libraries	Allows older clients to use multiple newer libraries in place of an older one.	Generally only useful when an older implementation splits into several newer libraries.